---
title: Accessibility
redirect_from:
  - /components/toast/accessibility/
---

## Accessibility

The Toast component has been designed with accessibility in mind, providing a non-intrusive way to display temporary notifications to users. It follows accessibility best practices to ensure all users, including those using assistive technologies, can perceive and understand these notifications.

### Accessibility props

| Name      | Type                               | Description                                                                                                                      |
| :-------- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
| role      | `"status" \| "alert"`              | The ARIA role for the toast. Use `"alert"` for important notifications requiring immediate attention                             |
| aria-live | `"polite" \| "assertive" \| "off"` | Controls how urgently screen readers announce the content. The difference between values is described in Best practices section. |

These attributes are passed through the `ariaProps` object in the second argument of the `createToast` function:

```jsx
createToast("Your message", {
  ariaProps: {
    role: "alert",
    "aria-live": "assertive",
  },
});
```

### Automatic accessibility features

- **Focus management**: Toasts do not steal focus from the user's current task, maintaining keyboard navigation flow
- **Animation pausing**: Hover over toasts pauses the dismissal countdown, giving users more time to read lengthy messages

### Keyboard and screen reader experience

- **Visual notifications**: Toasts appear visually and are automatically announced to screen readers
- **Keyboard focus**: Toasts don't steal keyboard focus, allowing users to continue their current task
- **Mouse hover**: Pauses the toast dismissal timer
- **Mouse leave**: Resumes the toast dismissal timer

### Best practices

- **Keep messages concise**: Use clear, brief messages that can be quickly read and understood
- **Use appropriate roles**:
  - Use `role="status"` for non-critical information (default)
  - Use `role="alert"` only for important messages requiring immediate attention
- **Set appropriate aria-live values**:
  - Use `aria-live="assertive"` only for critical messages, interrupts the current task to announce the message
  - Use `aria-live="polite"` for most messages (default), waits for finish of prioritized announcements
  - Use `aria-live="off"` for toasts that are not so urgent, announces the message once current task is finished and trigger element still has focus (if exists)
- **Avoid too many toasts**: Limit the number of simultaneous toast notifications to prevent overwhelming users
- **Consider message duration**: Set an appropriate `dismissTimeout` based on message length and importance
- **Provide context**: Ensure messages make sense when announced out of context by screen readers
- **Translation**: Ensure all toast content is properly localized for international users

### Examples

#### Basic informational toast

```jsx
import { createToast } from "@kiwicom/orbit-components/lib/Toast";

createToast("Your changes have been saved");
```

Screen reader announces: "Your changes have been saved" (with default `role="status"` and `aria-live="polite"`)

#### Critical error toast

```jsx
import { createToast } from "@kiwicom/orbit-components/lib/Toast";
import AlertCircle from "@kiwicom/orbit-components/lib/icons/AlertCircle";

createToast("Payment unsuccessful. Please try again.", {
  icon: <AlertCircle />,
  ariaProps: {
    role: "alert",
    "aria-live": "assertive",
  },
});
```

Screen reader announces immediately: "Payment unsuccessful. Please try again."

#### Promise-based toast

```jsx
import { createToastPromise } from "@kiwicom/orbit-components/lib/Toast";

createToastPromise(
  saveDataPromise,
  {
    loading: "Saving your changes...",
    success: "Changes saved successfully",
    error: "Failed to save changes",
  },
  {
    // Global aria props for all states
    ariaProps: {
      role: "status",
      "aria-live": "polite",
    },
    // Override aria props for error state
    error: {
      ariaProps: {
        role: "alert",
        "aria-live": "assertive",
      },
    },
  },
);
```

Screen reader announces the appropriate message based on the promise state, with the error state having higher priority.
